fix: updated docs styling #2552
Conversation
lolrobbe2
changed the title
|
|
||
| ```lua | ||
| architecture ("value") | ||
| architecture ("arch") |
There was a problem hiding this comment.
Both "value"/"arch" are wrong there (not valid value). value/arch would be good (variable might have a correct value)
There was a problem hiding this comment.
the idea is to be able to extract the name and get the following:
function architecture(arch) endThere was a problem hiding this comment.
It is the quotes that bore me (which shouldn't avoid the name extraction).
Some APIs accept mostly any strings, some quote are OKish, some expect specific string, and providing unexpected ones is confusing IMO.
architecture ("value") was already wrong, and should have been architecture (value) (or architecture ("%{value}")).
And then you should only have renamed 'value' to 'arch'.
| --- | ||
| title: basedir | ||
| description: Sets the base directory for a configuration | ||
| keywords: [premake, basedir, base directory, path, configuration] |
There was a problem hiding this comment.
Seems you use config in other places
| --- | ||
| title: buildcustomizations | ||
| description: Imports custom .props files for Visual Studio. | ||
| keywords: [premake, buildcustomizations, visual studio, props, project] |
There was a problem hiding this comment.
'project' versus 'project config'?
|
@Jarod42 maby i should also add a file wich describes the docs styling. and could you help me figure out a way to enforce this maby via CI? |
|
@Jarod42 i started work on a js script that cheks the documentation format and logs potential errors and fails when errors are found. i am also creating a helper script to streamline generating documentation files |
|
if you have a script to check documentation, it should probably be called from https://github.com/premake/premake-core/blob/master/.github/workflows/website.yml to ensure consistency. |
yes that is the goal, it is just a js script so can be run in the website task. and logs precise errors when things are wrong |
| @@ -1,17 +1,25 @@ | |||
| --- | |||
| title: callingconvention | |||
| description: Sets whether or not the compiler should build STL modules. | |||
There was a problem hiding this comment.
I'm against adding title and description front-matters when they are not necessary. If not set, the title of the page is its filename and it's fine for 99% of our pages. Same goes for description. Docusaurus takes first paragraph as a description so there is no need to repeat it in the front-matter. It's bug-prone and this PR proves it. This description is copied from another page :)
| --- | ||
| title: callingconvention | ||
| description: Sets whether or not the compiler should build STL modules. | ||
| keywords: [premake, callingconvention, cdecl, fastcall, stdcall, vectorcall, function calling convention, compiler, project config] |
There was a problem hiding this comment.
What is your algorithm for generating keywords for every page? Do they help you in any way? Because I am pretty much sure they will not affect searchability of our docs at all.
3 participants
What does this PR do?
this pr aims to rectify #2551
format:
params non determenistic:
for params wich are not deterministic IE have standard values like architecture the following style is used:
params deterministic:
for params wich are deterministic a MD table is used:
for architecture:
arch is the enum/param name